home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / tppcx.arc / PCX.DOC < prev    next >
Text File  |  1991-01-29  |  26KB  |  562 lines
  1. PCX.TPU  -  TPv6.0 Object-Oriented unit for displaying or saving PCX format
  2.             picture files on Hercules, EGA, VGA, or compatible adapters.
  3.  
  4. ╔═════════╗
  5. ║ BasePCX ║█
  6. ╚═════════╝█
  7.   ▀▀▀▀▀▀▀▀▀▀
  8. The BasePCX object provides basic PCX functions that are independant of the
  9. adapter type. This object is used in the abstract to create device dependant
  10. objects.
  11.  
  12. RESTRICTIONS ─────────────────────────────────────────────────────────────────
  13.  
  14. This unit is for use only with EGA/ECM, VGA, and Hercules compatible devices.
  15. Extended image files, ones exceeding the displaying device resolution,
  16. cannot be read at this time and will generate a PCXError. Future versions
  17. will handle panning. When reading a file which was created by a higher
  18. resolution device than the device displaying the file, it may still be read
  19. as long as the image dimensions do not exceed the display device resolution.
  20. The image size can be set in the paint program before creating the picture if
  21. you wish to make the PCX file compatible with several devices.
  22.  
  23. FIELDS ───────────────────────────────────────────────────────────────────────
  24.  
  25. PCXError    PcxError: byte;                                       Read only
  26.  
  27.             Set to constant equivalent if an error is encountered in reading
  28.             writing from object.
  29.             See: BasePCX.GetPCXError
  30.  
  31. Loaded      Loaded: boolean;                                      Read/Write
  32.  
  33.             Set to false at object initialization, it is set to true after a
  34.             picture has been loaded. It tells internal methods that a
  35.             picture has been loaded and if the image or portion of the image
  36.             is saved as another file, the existing color mapping is written
  37.             to the new file.
  38.             See: BasePCX.PCXLoaded
  39.  
  40. Hdr         Hdr: Header;                                          Read only
  41.  
  42.             Record containing information pertaining to the picture file. The
  43.             record is filled when reading a PCX file from a 128 byte file
  44.             header that precedes the actual image data. The last 58 bytes of
  45.             the file header are just filler, so these are ignored. The header
  46.             record contains the following fields:
  47.                   Maker: integer;
  48.                         Code that specifies the picture generating program
  49.                         conforms to PCX format. PCXError set if incorrect
  50.                         maker, further methods halted.
  51.                   Version: integer;
  52.                         Code stating what PCX format version the following
  53.                         picture file was created with. PCXError set if incor-
  54.                         rect version, further methods halted.
  55.                   Encoding: integer;
  56.                         Code indicating the compression type of the following
  57.                         picture file. PCXError set if not run-length encoded,
  58.                         further methods halted.
  59.                   bpp: integer;
  60.                         Number indicating the number of bits per pixel per
  61.                         plane. Not used in this unit version.
  62.                   xmn: integer;
  63.                         Number setting the upper left horizontal coordinate
  64.                         of following picture.
  65.                         See: BasePCX.GetXmn
  66.                   ymn: integer;
  67.                         Number setting the upper left vertical coordinate of
  68.                         following picture.
  69.                         See: BasePCX.GetYmn
  70.                   xmx: integer;
  71.                         Number setting the lower right horizontal coordinate
  72.                         of following picture.
  73.                         See: BasePCX.GetXmx
  74.                   ymx: integer;
  75.                         Number setting the lower right vertical coordinate of
  76.                         following picture.
  77.                         See: BasePCX.GetYmx
  78.                   HRes: integer;
  79.                         Number indicating the horizontal resolution of the
  80.                         device that the created the picture file.
  81.                   VRes: integer;
  82.                         Number indicating the vertical resolution of the
  83.                         device that created the picture file.
  84.                   CMap: TripletArray;
  85.                         2-dimensional array ( 16 triplets ) containing palette
  86.                         information for the following picture. If the
  87.                         following image is color and the displaying device
  88.                         is an EGA/VGA, the color map is used and the palette
  89.                         is set accordingly, if requested in the Show method.
  90.                         Otherwise CMap is ignored.
  91.                   Reserved: byte;
  92.                         Filler number reserved by ZSoft.
  93.                   NPlanes: byte;
  94.                         Number of picture planes used to create the image.
  95.                         Essentially establishes the differance between a mono
  96.                         and color picture.
  97.                         See: BasePCX.IsMultiPlane
  98.                   NBpl: integer;
  99.                         Number telling the object how many bytes are used to
  100.                         store a single horizontal line of the picture in
  101.                         memory.
  102.                   Palett: integer;
  103.                         Number for interpreting the palette. 0 = gray scale
  104.                         iamge. 1 = color image.
  105.  
  106. Page        Page: byte;                                           Read only
  107.  
  108.             Used when reading PCX files, it determines which video page the
  109.             image is written to. Since the object uses direct memory, the
  110.             picture is written to the page requested regardless of the
  111.             active page setting. The visual page setting still maintains
  112.             display control.
  113.  
  114. PFile       PFile: pointer;                                       Read only
  115.  
  116.             Points to dynamic memory area where entire PCX file has been
  117.             read into ram. This increases decoding speed by reading the
  118.             compressed image data from ram instead of thru file I/O.
  119.             PCXError will be set if there is not enough memory available.
  120.             See: BasePCX.Done
  121.  
  122. SizeF       SizeF: longint;                                       Read only
  123.  
  124.             Size of PCX file read into ram. Used for disposing memory when
  125.             destructing the object.
  126.  
  127. Buf         Buf: PBuf;                                            Read only
  128.  
  129.             Pointer to  dynamic variable (128 byte) which holds one complete
  130.             decoded/encoded scan line during the decoding or encoding
  131.             method.
  132.  
  133. Offset      Offset: POffset;                                      Read only
  134.  
  135.             One-dimensional 480 byte array holding the video memory offset
  136.             address to the beginning of each horizontal scan line. The
  137.             offsets are calculated based on the object and not the creating
  138.             device.
  139.  
  140. Display     Display: DisplayRec;                                  Read/Write
  141.  
  142.             Record variable set by descendant objects upon initialization
  143.             containing display adapter information. Correct information is
  144.             set based on the descendant type and not the creating device.
  145.             The record contains the following fields:
  146.  
  147.                   SegBase: word;
  148.                         Base address to video memory.
  149.                   Page0: word;
  150.                         Offset from SegBase for start of video page 0.
  151.                   Page1: word;
  152.                         Offset from SegBase for start of video page 1.
  153.                   HorizRes: integer;
  154.                         Horizontal resolution of specific adapter.
  155.                         Informative only, not used.
  156.                   VertRes: integer;
  157.                         Vertical resolution of specific adapter.
  158.                         Informative only, not used.
  159.                   BytesPerLine: integer;
  160.                         Number of bytes required for one scan line per plane.
  161.                         Informative only, not used. See: Hdr field.
  162.                   NoColors: integer;
  163.                         Number of palette entries available.
  164.                         Informative only, not used.
  165.  
  166. f           f: file;                                              Read only
  167.  
  168.             Assigned to PCX file and used during decoding or encoding.
  169.             During decoding, the file variable is closed immediately after
  170.             reading into ram. While encoding, however, the file must remain
  171.             open until the process is completed thus requiring it to be a
  172.             field of the object.
  173.  
  174.  
  175. METHODS, PUBLIC ──────────────────────────────────────────────────────────────
  176.  
  177. Init        constructor Init;
  178.  
  179.             Initializes all internal pointers to nil. Calls the FillOffsets
  180.             procedure. Sets PCXError to PCXError0.
  181.             OverRide: Always
  182.  
  183. Done        destructor Done; virtual;
  184.  
  185.             Disposes of the Offset and PFile allocations.
  186.             OverRide: Mostly
  187.  
  188. Show        procedure Show( Filename: FStr; PageNo: byte; UsePal: boolean );
  189.  
  190.             Displays requested PCX file as assigned by Filename on the page
  191.             specified by PageNo (0 or 1 only) using the color mapping as
  192.             specified in the PCX file header if UsePal is set to true. If
  193.             errors are encountered, PCXError is set accordingly and the
  194.             procedure is exited. Only pages 0 and 1 are valid in this version.
  195.             If UsePal is set to false, the object uses the default settings
  196.             as specified in the EGA_Pal constant. These settings are the same
  197.             as a paint program's default settings.
  198.             Any PCX file created on a Hercules, EGA, or VGA adapter can be
  199.             displayed on any one of the same adapters. That is to say, you
  200.             can display a monochrome image on an EGA adapter, or display an
  201.             EGA image on a Hercules adapter, or etc. with the following
  202.             limitations/conditions: The PCX file vertical size cannot exceed
  203.             the display adapter's resolution. Images will be distorted when
  204.             displayed on an adapter differant then the creating device. When
  205.             displaying a mono picture on a color adapter, set UsePal to
  206.             false.
  207.             It is important to note the following: When UsePal is set to
  208.             true, the PCX file may change the palette. All occurances of a
  209.             specific color within the program will be immediately set to the
  210.             new value. Also, the object instance does not reset the palette
  211.             when it it destructed. It remains more versatile to control the
  212.             palette outside the object. Some paint programs, for unknown
  213.             reasons, do some strange things with the palette settings. So if
  214.             a display doesn't turn out as expected, try setting UsePal to
  215.             false. See EGA.DOC for procedure on resetting the palette to the
  216.             default condition. See also: BasePCX.Save
  217.             This method calls OpenFile; if the file opens without errors,
  218.             calls GetHeader, SetPal (if requested), Decode.
  219.             See also: BasePCX Page field description
  220.  
  221. Save        procedure Save( x1, y1, x2, y2: integer; Filename: FStr );
  222.  
  223.             Saves image in viewport specified by upper left coordinates
  224.             (x1,y1) and lower right coordinates (x2,y2) to disk in PCX format
  225.             with the specified Filename. At this time, it saves only an image
  226.             displayed on page 0 of any adapter. If a PCX picture has been
  227.             previously loaded and all/portion of the same picture is being
  228.             saved, the same color mapping information is written to the new
  229.             file IF it was displayed with UsePal set to true AND the object
  230.             was not destructed between the calls to Show and Save. Otherwise
  231.             the default EGA palette is written. This method is graphics
  232.             adapter specific, the correct object must be used depending on
  233.             the graphics card of creating device. A VGA adapter can be set to
  234.             640x350 or 640x480 resolution. It is important to note that the
  235.             image saved will, most of the time, not be to the exacting
  236.             coordinates specified. This is due to the fact that each bit
  237.             represents one pixel (8 pixels per byte). Since there are always
  238.             an integral number of bytes, the image must start and stop at
  239.             multiples of 8.
  240.             This method calls OpenFile with a newfile request; if no errors
  241.             are reported, calls WriteHeader, Encode.
  242.             See also: BasePCX.Show
  243.  
  244. GetPicVp    procedure GetPicVp( var PicVp: viewporttype );
  245.  
  246.             Returns displayed image boundaries in the PicVp variable. These
  247.             coordinates are read from the PCX header information.
  248.  
  249. GetXmn      function GetXmn: integer;
  250.  
  251.             Returns upper left horizontal corner of picture.
  252.  
  253. GetYmn      function GetYmn: integer;
  254.  
  255.             Returns upper left vertical corner of picture.
  256.  
  257. GetXmx      function GetXmx: integer;
  258.  
  259.             Returns lower right horizontal corner of picture.
  260.  
  261. GetYmx      function GetYmx: integer;
  262.  
  263.             Returns lower right vertical corner of picture.
  264.  
  265. IsMulti-
  266. Plane       function IsMultiPlane: boolean;
  267.  
  268.             Returns true if picture read is a multi-plane image. Generally
  269.             used to determine the differance between a color or B/W image.
  270.  
  271. GetPCXError function GetPCXError: byte;
  272.  
  273.             Returns with numeric code cooresponding to type of error
  274.             encountered during object implementation, if any, and can be
  275.             compared to the following constants:
  276.  
  277.                   0 = No error
  278.                   1 = File not found
  279.                   2 = Not enough memory for picture buffer
  280.                   3 = Error reading PCX file into RAM
  281.                   4 = Multi-plane image encountered,display adapter for
  282.                       single plane only
  283.                   5 = Not a valid PCX file
  284.                   6 = Incorrect PCX version. Must be v3.0 or greater
  285.                   7 = Not enough memory for Offset Buffer
  286.                   8 = Unable to open new file
  287.                   9 = Encoding error
  288.                  10 = Image exceeds 64k limit.
  289.                  11 = Image exceeds display capabilities.
  290.  
  291. PCXLoaded   function PCXLoaded: boolean;
  292.  
  293.             Returns true if a PCX picture has been loaded from disk and is
  294.             currently displayed. ( whether invisble or not ) Primarily used
  295.             internally for resetting the EGA.
  296.  
  297. METHODS, PRIVATE ─────────────────────────────────────────────────────────────
  298.  
  299. OpenFile    procedure OpenFile( Filename: FStr; NewFile: boolean;
  300.                                 var Ok: boolean );
  301.  
  302.             Opens requested PCX file. When reading a file, Newfile is set
  303.             to false and the file is read into ram and then closed. When
  304.             writing a file, NewFile is set to true and the file is
  305.             rewritten. No action is taken if the file currently exists and
  306.             the method overwrites, always. Action should be taken prior to
  307.             writing a PCX file to determine if an existing file exists. Ok
  308.             returns true if normal file procedures (IOResult) performed
  309.             correctly.
  310.  
  311. GetHeader   procedure GetHeader;
  312.  
  313.             When reading a PCX file, method decodes header information and
  314.             sets internal fields accordingly.
  315.  
  316. SetPal      procedure SetPal; virtual;
  317.  
  318.             Abstract method only.
  319.             OverRide: Always
  320.  
  321. Decode      procedure Decode; virtual;
  322.  
  323.             Abstract method only.
  324.             OverRide: Always
  325.  
  326. DecodeRow   procedure DecodeRow( var Index: integer );
  327.  
  328.             Decodes compressed image data contained in the memory area
  329.             pointed to by Buf. Index is a counter variable keeping track of
  330.             the current position in memory pointed to by PFile.
  331.  
  332. WriteRow    procedure WriteRow( row: integer );
  333.  
  334.             Writes uncompressed image data to video memory at the page
  335.             requested and plane setting. The row cooresponds to the Offset
  336.             array index for addressing.
  337.  
  338. ReadRow     procedure ReadRow( row, sbyt: integer; var inBuf: PBuf );
  339.  
  340.             Reads a single scan line, starting at offset row + sbyt, into the
  341.             inBuf variable based on the row requested and plane setting. Row
  342.             cooresponds to the Offset array index for addressing. Sbyt is
  343.             the byte number within the row to start reading from.
  344.  
  345. WriteHeader procedure WriteHeader;
  346.  
  347.             Writes header infromation to a new PCX file. Palette information
  348.             is written as a default configuration, normal to the creating
  349.             device. Future versions will allow for palette manipulation.
  350.  
  351. FillOffsets function FillOffsets: boolean; virtual;
  352.  
  353.             Abstract method only.
  354.             OverRide: Always.
  355.  
  356. Encode      function Encode(SRow, ERow: integer; sbyt: byte): integer;virtual;
  357.  
  358.             Abstract method only.
  359.             OverRide: Always
  360.  
  361. EncPut      function EncPut( byt, cnt: byte ): integer;
  362.  
  363.             Writes a data byte (byt) to the PCX file (f). Cnt is a repeat
  364.             rate of the data byte. If the repeat rate is greater than one,
  365.             the cnt variable is coded and written to the file prior to the
  366.             data byte. EncPut returns with the number of bytes written to
  367.             the file (1 or 2) for keeping track of the total number written.
  368.  
  369. EncodeLine  function EncodeLine( inBuf: PBuf; inLen: integer ): boolean;
  370.  
  371.             Compresses the data contained in the inBuf variable. The amount
  372.             of data to compress is determined by the inLen variable. Reads
  373.             the data in inBuf a byte at a time and counts the number of
  374.             times the data is repeated, if any. It calls EncPut when the
  375.             data stops repeating (byte mismatch) to write to the PCX file.
  376.             EncodeLine returns true if the encoding process was successful.
  377.  
  378. GetByte     function GetByte( n: integer ): byte;
  379.  
  380.             Retrieves the byte value from the memory pointed to by PFile at
  381.             position n.
  382.  
  383. GetInteger  function GetInteger( n1, n2: integer ): integer;
  384.  
  385.             Retrieves the integer value from the memory pointed to by PFile
  386.             at positions n1 and n2.
  387.  
  388. FillOffsets function FillOffsets: boolean; virtual;
  389.  
  390.             First determines if enough memory is available for reading the PCX
  391.             file into ram, then calculates video memory offset addresses based
  392.             on descendant type. Calculations are stored in the Offset field
  393.             with each horizontal scan line number cooresponding with the
  394.             array number. ie: scanline 0 = Offset[0], scanline 1 = Offset[1]
  395.             Method returns true if memory was allocated. If not enough
  396.             memory is available, the method returns false and the Init
  397.             constructor fails, returning NIL to the host.
  398.  
  399. Decode      procedure Decode; virtual;
  400.  
  401.             Decodes compressed image data based on header information.
  402.             Allocates memory for Buf, determines if image is multiplane,
  403.             calls EGA_SetPlane_Write, DecodeRow, WriteRow.
  404.             OverRide: Always
  405.  
  406.       ┌─────────┐
  407.       │ BasePCX │
  408.       └────┬────┘
  409.      ┌─────┘
  410. ╔════╧════╗
  411. ║ HercPCX ║█
  412. ╚═════════╝█
  413.   ▀▀▀▀▀▀▀▀▀▀
  414. The HercPCX object provides the device dependant methods for creating PCX
  415. format files on Hercules graphics adapters. It can create PCX files on any
  416. monochrome graphics devices whose base video address is $B000, however if
  417. multiple pages are not supported you must be sure to pass only page 0 to the
  418. inherited Show method.
  419.  
  420. METHODS, PUBLIC ──────────────────────────────────────────────────────────────
  421.  
  422. Init        constructor Init;
  423.  
  424.             Checks for the presence of an EGA/VGA adapter by seeing if the
  425.             EGACard variable in the EGA unit is true or false. If EGACard is
  426.             true the Init contructor fails, since a HercPCX instance on an
  427.             EGA/VGA adapter would not display properly. If an EGA/VGA is not
  428.             detected, the PCX units Display constant is set to equal the
  429.             HERC_Attr constant and BasePCX.Init is called. If the
  430.             BasePCX.Init method returns false, this constructor fails.
  431.  
  432. Done        destructor Done; virtual;
  433.  
  434.             Calls BasPCX.Done destructor.
  435.  
  436. METHODS, PRIVATE ─────────────────────────────────────────────────────────────
  437.  
  438. Decode      procedure Decode; virtual;
  439.  
  440.             Allocates/disposes of memory for the Buf pointer.
  441.             Checks with the IsMultiPlane method and if true decodes the
  442.             compressed data based on a multi-plane image else decodes
  443.             normally. Loops thru DecodeRow and WriteRow for each scan line
  444.             from Hdr.ymn to Hdr.ymx.
  445.  
  446. GetRow      procedure GetRow( r, sbyt: integer; var inBuf: PBuf );
  447.  
  448.             Calls ReadRow with r (row to read), sbyt (starting byte in row),
  449.             and inBuf (memory area to read into).
  450.  
  451. Encode      function Encode(SRow, ERow: integer; sbyt: byte): integer;virtual;
  452.  
  453.             Loops from SRow to ERow calling GetRow with scan line number
  454.             cooresponding to the loop count and sbyt starting postion. Calls
  455.             EncodeLine with the data retrieved from GetRow. If EncodeLine
  456.             returned true, goes to top of loop, else sets itself to PCXError9
  457.             and exits. If Encode completes correctly it returns to the calling
  458.             method set to 0.
  459.  
  460. FillOffsets function FillOffsets: boolean; virtual;
  461.  
  462.             Fills the Offset variable with the video memory address to the
  463.             start of each scan line. The Offset array elements coorespond to
  464.             the scan line number. ie: Offset^[0] = scan line 0, Offset^[1] =
  465.             scan line 1, etc. These addresses are calculated based on the
  466.             Hercules graphics adapter, which is in an interlaced pattern.
  467.  
  468.       ┌─────────┐
  469.       │ BasePCX │
  470.       └────┬────┘
  471.      ┌─────┴─────┐
  472. ┌────┴────┐ ╔════╧════╗
  473. │ HercPCX │ ║ EgaPCX  ║█
  474. └─────────┘ ╚═════════╝█
  475.               ▀▀▀▀▀▀▀▀▀▀
  476. The EgaPCX object provides the device dependant methods for reading or
  477. creating PCX format files on EGA/VGA graphics adapters on pages 0 and 1 only
  478. in 640 x 350 resolution mode.
  479.  
  480. METHODS, PUBLIC ──────────────────────────────────────────────────────────────
  481.  
  482. Init        constructor Init;
  483.  
  484.             Checks with EGA unit's EGACard constant and if not true, the
  485.             constructor Fails. If EGACard returns true, Display is set to
  486.             EGA_Attr and BasePcx.Init is called.
  487.  
  488. Done        destructor Done; virtual;
  489.  
  490.             Calls BasePCX.Done destructor.
  491.  
  492. METHODS, PRIVATE ─────────────────────────────────────────────────────────────
  493.  
  494. SetPal      procedure SetPal; virtual;
  495.  
  496.             Sets palette to values contained in Hdr.CMap as read from the
  497.             PCX file header. Calls EGA unit, EGA_SetRGBPalette procedure
  498.             with Hdr.CMap component values.
  499.  
  500. Decode      procedure Decode; virtual;
  501.  
  502.             Allocates/disposes of memory for the Buf pointer.
  503.             Checks with the IsMultiPlane method and if true decodes the
  504.             compressed data based on a multi-plane image else decodes
  505.             according to single plane data. Loops thru DecodeRow and WriteRow
  506.             for each scan line from Hdr.ymn to Hdr.ymx.
  507.  
  508. GetRow      procedure GetRow( Plane, r, sbyt: integer; var inBuf: PBuf );
  509.  
  510.             Retrieves video memory data for compressing.
  511.             Calls EGA unit, EGA_SetPlane_Read with Plane (bit plane to read),
  512.             calls ReadRow with r (scanline/row to read), sbyt (starting byte
  513.             in row) and inBuf (memory area to read into).
  514.  
  515. Encode      function Encode(SRow, ERow: integer; sbyt: byte): integer;virtual;
  516.  
  517.             Loops from SRow to ERow calling GetRow with scan line number
  518.             cooresponding to the loop count and sbyt starting position. Calls
  519.             EncodeLine with the data retrieved from GetRow. If EncodeLine
  520.             returned true, goes to top of loop, else sets itself to PCXError9
  521.             and exits. If Encode completes correctly it returns to the calling
  522.             method set to 0.
  523.  
  524. FillOffsets function FillOffsets: boolean; virtual;
  525.  
  526.             Fills the Offset variable with the video memory address to the
  527.             start of each scan line. The Offset array elements coorespond to
  528.             the scan line number. ie: Offset^[0] = scan line 0, Offset^[1] =
  529.             scan line 1, etc. These addresses are calculated based on the
  530.             EGA/VGA graphics adapter, which is in a non-interlaced pattern.
  531.  
  532.       ┌─────────┐
  533.       │ BasePCX │
  534.       └────┬────┘
  535.      ┌─────┴─────┐
  536. ┌────┴────┐ ┌────┴────┐
  537. │ HercPCX │ │ EgaPCX  │
  538. └─────────┘ └────┬────┘
  539.             ╔════╧════╗
  540.             ║ VgaPCX  ║█
  541.             ╚═════════╝█
  542.               ▀▀▀▀▀▀▀▀▀▀
  543. The VgaPCX object provides the device dependant methods for reading or
  544. creating PCX format files on VGA graphics adapters on pages 0 and 1 only
  545. in 640 x 350 or 640 x 480 resolution modes.
  546.  
  547. Init        constructor Init;
  548.  
  549.             Checks with EGA unit's VGACard constant and if not true, the
  550.             constructor Fails. If VGACard returns true, Display is set to
  551.             EGA_Attr with VertRes set to 480 and BasePcx.Init is called.
  552.  
  553. Done        destructor Done; virtual;
  554.  
  555.             Calls BasePCX.Done destructor.
  556.  
  557. ──────────────────────────────────────────────────────────────────────────────
  558.  
  559. Compiled with Borland's Turbo Pascal v6.0
  560. Designed for ZSoft Corporation's PCX file format
  561. 29Jan91
  562.